《Codex 入门指南》

1	特别说明：此文由ChatGPT生成，后续由我本人编辑、修改而成。

0 引言：从驾驶员到塔台

1956 年，美国联邦航空管理局面临一个前所未有的难题：随着喷气式客机的普及，天空中的飞机数量激增，传统的目视管制方式——地面人员拿着望远镜盯着跑道——已经无法保障安全。他们的解决方案不是训练更多的飞行员，而是建立了一个全新的角色：空中交通管制员。管制员不驾驶任何一架飞机，但他同时监控数十架飞机的航线，协调冲突，确保每一架都安全着陆。从此，航空业的核心范式从“驾驶”转向了“调度”。

七十年后，软件开发正在经历类似的转变。

如果你用过 Cursor，你体验的是一种“副驾驶”模式：你坐在驾驶位写代码，AI 坐在旁边提建议。你输入一行，它补全下一行；你描述需求，它在你眼前修改文件。你始终“在环内”（Human-in-the-loop），每一步都亲眼看到、亲手确认。这很好，但它有一个根本限制——你一次只能飞一架飞机。

OpenAI Codex macOS App 提供了另一种可能：你从驾驶员变成了塔台。你不再逐行指导 AI 写代码，而是给出高层意图——“为这个项目添加用户管理模块”——然后 Codex Agent 在隔离环境中自主完成整个任务：分析代码库、规划方案、生成代码、运行测试，最终交给你一份完整的 diff 或 Pull Request。在 Codex 里，你可以同时启动多个 Agent 线程——一个在添加新 API，另一个在修复 Bug，第三个在生成测试——就像管制员同时引导多架飞机着陆。

这不是科幻畅想。OpenAI API 和开发者平台工程负责人 Sherwin Wu 在一次播客中透露：OpenAI 内部 95% 的工程师每天都在用 Codex，几乎 100% 的代码最初由 AI 生成。工程师们经常同时管理 10 到 20 个 Codex 线程并行推进，而使用 Codex 更多的工程师，提交的 PR 数量高出 70%。“从驾驶员到塔台”已经不是比喻——它正在 OpenAI 内部发生。

但当你从驾驶舱走上塔台，一个新的问题随之出现：你怎么知道每架飞机都在正确的航线上？

在 Cursor 里，答案很简单——你看到每一行代码在你眼前生成，不对就立刻纠正。但在 Codex 里，Agent 是在后台自主工作的，你不可能盯着每一行。这时候，你需要的不是更好的眼力，而是更好的“雷达系统”：测试覆盖率是你的雷达屏幕，CI 流水线是你的预警系统，AGENTS.md 中的项目规范是你画好的航线。这些基础设施在以前是“锦上添花”的好习惯，在 Agent 式编程时代则变成了“没有就不能起飞”的硬性前提。

换一种说法：你的工程基本功不是被 AI 取代了，而是被 AI 放大了。基础好，效率倍增；基础差，混乱也倍增。

本指南面向有经验的 Java 后端工程师，假定你已熟悉 IDE 和大语言模型的基本用法。我们不会讲“什么是 Prompt”，而是聚焦于：如何在 Codex 中高效地委派任务、管理多个 Agent、以及建立可靠的验证闭环——从驾驶员思维，切换到塔台思维。

1 Codex 全景：不止是一个 App

在深入具体操作之前，有必要先鸟瞰一下 Codex 的全貌。

很多人第一次听说 Codex 时，以为它只是一个 macOS 桌面应用。这就像 1990 年代的人第一次听说“互联网”时，以为它只是“能发邮件的东西”。实际上，Codex 已经发展为一个多形态的产品家族——就像同一支军队的陆海空天四个军种，共享同一套指挥体系（codex-1 模型 + AGENTS.md 规范），但适配不同的作战环境。

1.1 四种形态

Codex App（macOS 桌面应用）——本文的主角。图形化界面，支持 Worktree / Cloud 多线程并行，内置 Review 面板和终端。如果你喜欢可视化操作，这是最直观的入口。

Codex CLI（开源命令行工具）——终端党的最爱。一行命令就能启动 Agent：codex "为 UserService 添加分页查询"。开源在 GitHub（github.com/openai/codex），你可以查看源码、提交 Issue，甚至贡献代码。CLI 也是 CI/CD 集成的基础——后面的“团队协作”一章会详细讨论。

Codex IDE 扩展（VS Code / Cursor 插件）——在编辑器侧边栏直接使用 Codex Agent，无需切换窗口。它把 Codex 的异步 Agent 能力嵌入了你最熟悉的开发环境。对于已经在用 Cursor 的开发者来说，这意味着你可以在同一个 IDE 里同时使用 Cursor 的实时补全和 Codex 的后台 Agent。

Codex Web（浏览器版）——通过 chatgpt.com/codex 访问，无需安装任何软件。连接你的 GitHub 仓库后，直接在浏览器里委派任务、审查 PR。适合不在工位时快速处理紧急任务，或者团队中非开发角色（如 PM）查看 Agent 工作进度。

1.2 codex-1：专为编程优化的推理模型

驱动所有四种形态的是同一个引擎：codex-1——一个基于 o3 优化的软件工程专用模型。

与通用的 GPT 系列不同，codex-1 在三个方面做了专门强化：第一，深度代码推理——它能理解大型代码库的全局架构，而不仅仅是当前文件的上下文；第二，工具使用——它原生支持读写文件、执行 Shell 命令、运行测试，而不是简单地“生成文本”；第三，可验证输出——它会引用终端日志、测试结果作为自己工作的证据，而不是要你盲目信任。

这也解释了为什么 Codex 的任务通常需要 1–30 分钟完成，而不是像 ChatGPT 那样秒回——因为 codex-1 在执行任务时会经历完整的“分析-规划-编码-测试-修正”循环，而不是一次性生成答案。

1.3 本文的聚焦

四种形态共享相同的核心概念：三种模式（Local / Worktree / Cloud）、AGENTS.md 配置、安全沙箱、Skills 技能系统。本文以 Codex App 为主线展开——它的图形界面最适合初次接触者建立直觉。但文中涉及的所有理念和技巧，同样适用于 CLI、IDE 扩展和 Web 版。在涉及关键操作时，我会顺带提及 CLI 的等价命令，方便终端用户参考。

2 三种模式：信任的光谱

管理学中有一个经典概念叫“委派阶梯”（Delegation Ladder），描述的是上级把工作交给下级时，信任和自主权的不同层级：最低一级是“我说你做，做完给我看”；中间一级是“你自己做，但在独立空间里做，做完我审查”；最高一级是“你全权负责，做完直接交付”。

Codex 的三种运行模式——Local、Worktree、Cloud——恰好对应了这条信任阶梯的三个台阶。

2.1 Local 模式：我说你做

Local 模式是信任的最低级：Agent 直接在你当前的项目目录上工作，所有修改即时生效，就像你自己在编辑文件一样。你全程看着它，随时可以叫停。

适合的场景： 改一个配置、加一行注解、快速试验一个想法——那些即使搞砸了也能用 git checkout 秒恢复的小事。

Java 项目提示： Local 模式的好处是 Agent 修改代码后，你可以直接在内置终端运行 mvn compile 或 ./gradlew build 验证——不需要额外配置依赖环境，因为所有依赖都在你的本地仓库里。

CLI 等价： codex --sandbox workspace-write "你的指令" 直接在当前目录工作，效果与 App 的 Local 模式相同。

但 Local 模式有一个明显的限制：没有隔离。Agent 的改动和你自己未提交的改动混在一起，如果它改错了关键文件，你得自己收拾残局。所以在使用前，确保你的工作区是干净的。

2.2 Worktree 模式：你自己做，做完我审查

1970 年代，丰田在制造业引入了一个激进的理念：每个工位都可以拉一根绳子叫停整条生产线（安灯系统）。这个看似降低效率的做法，实际上大幅提升了质量——因为问题在发生的瞬间就被发现和隔离，而不是等到成品出厂后才召回。

Worktree 模式体现了类似的哲学。每次启动新线程时，Codex 自动创建一个 Git worktree——你仓库的一个隔离副本。Agent 在这个独立空间里自由发挥，而你的主分支纹丝不动。做完了，你在 Review 面板里逐行审查 diff，满意了才合并；不满意，丢弃整个 worktree 就行，零成本。

这是 Codex 最核心的能力所在。 你可以同时开三个线程：

线程 1：在 UserController 中添加分页查询接口
线程 2：为 OrderService 补充单元测试
线程 3：重构 PaymentService，将硬编码的配置提取到 application.yml

三个 Agent 各自在独立的 worktree 上工作，互不干扰。这就像你同时委派了三个开发者，各自在自己的分支上干活。你只需要在他们提交 PR 时做审查。

Java 项目提示： 新的 worktree 默认不包含构建产物（target/ 目录为空）。如果 Agent 需要运行测试，你需要在 Codex 的 Local Environment 配置中设置初始化脚本：

1	mvn dependency:resolve -q && mvn compile -q

这样每次创建新 worktree 时会自动下载依赖并编译，确保 Agent 可以正常运行测试。

CLI 等价： codex --full-auto "你的指令" 启动 Auto 模式（workspace-write + on-request 审批），Agent 在工作区内自由操作。

2.3 Cloud 模式：你全权负责

2020 年，SpaceX 的猎鹰 9 号成为第一枚完全自主着陆的轨道级火箭。从发射到着陆，无需任何人类遥控操作——飞行计算机根据预设参数和实时传感器数据自行完成一切。但这不意味着工程师们在发射后就去喝咖啡了。他们事先做了大量工作：编写飞行程序、设置安全边界、模拟各种故障场景。自主执行的前提是充分的事前准备。

Cloud 模式就是 Codex 的“自主着陆”模式。Codex 在 OpenAI 的云端沙盒中克隆你的远程仓库，Agent 在完全隔离的云环境中执行任务，完成后自动提交 Pull Request。你的电脑可以关机，Agent 照样工作。

Cloud 模式有一个独特优势：Agent 可以自动执行命令。 在 Local 和 Worktree 模式中，出于安全考虑，Agent 不会自行运行 Shell 命令（比如 mvn test），需要你手动执行。但在 Cloud 的沙盒里，一切都是隔离的，可以放心让 Agent 自主构建和测试。你在 AGENTS.md 中告诉它：

## 构建与测试
- 构建命令：`mvn clean package -DskipTests`
- 测试命令：`mvn test`
- 代码格式检查：`mvn spotless:check`

Cloud Agent 会执行这些命令，确保代码编译通过、测试全绿，然后才生成 PR。就像猎鹰 9 号的飞行计算机——事前把规则定义好，执行过程完全自主。

CLI 等价： Cloud 模式目前主要通过 Codex App 和 Web 版使用。CLI 用户可以通过 codex --sandbox danger-full-access 在本地模拟类似的全自主执行（但请注意，这移除了所有安全限制，仅建议在容器化环境中使用）。

前置条件： Cloud 模式需要你提前配置 GitHub 仓库权限，并在仓库中放置 AGENTS.md 文件（第 4 章详述）。

2.4 怎么选？

Local — 无隔离，直接改本地文件。单线程，需手动确认命令执行。适合小改动，改完即生效。

Worktree — 独立 Git 工作树隔离。支持多线程并行，需手动确认命令执行。适合中等功能开发，改动在工作树分支上，审查后合并。

Cloud — 完全隔离的云端沙盒。支持多线程并行，Agent 可自动执行命令。适合大型/长时间任务，完成后自动提交 PR，几乎不占本地资源。

本质上，这三种模式是信任和自主权的渐进——从“你做我看”到“你做完我审查”再到“你全权负责”。日常开发建议以 Worktree 为主——它就像丰田的安灯系统，给了 Agent 充分的行动空间，同时保留了你随时“拉绳叫停”的权力。

3 安全模型：信任，但要验证

冷战时期，美国总统里根在与苏联谈判核裁军条约时，反复引用一句俄罗斯谚语：“信任，但要验证”（Trust, but verify）。这句话精准地概括了核查机制的哲学——签了条约不等于可以高枕无忧，你需要卫星监控和实地核查来确保对方真的在裁军。

Codex 的安全模型体现了完全相同的哲学。它不是让你在“完全信任”和“完全不信”之间做非此即彼的选择，而是提供了一套分层的控制机制——你可以根据任务的风险等级，精确调节给 Agent 的自由度。

3.1 两层防线：沙箱与审批

Codex 的安全控制由两层机制协同工作：

第一层：沙箱（Sandbox）——限制 Agent 在技术上“能做什么”。在 macOS 上，Codex 使用 Seatbelt 安全策略（类似 iOS 的 App 沙盒机制），将 Agent 的文件访问限制在工作目录内；在 Linux 上则使用 Landlock + seccomp 实现类似隔离。Cloud 模式更彻底——Agent 运行在 OpenAI 托管的容器中，与你的本机系统完全隔绝。

第二层：审批策略（Approval Policy）——控制 Agent 在行动前“需不需要问你”。即使沙箱允许某个操作，审批策略也可以要求 Agent 在执行前先获得你的确认。

这就像实验室的生物安全等级（BSL）——BSL-1 是开放实验台，实验员可以自由操作；BSL-4 是全封闭负压环境，每个动作都需要严格审批。大多数日常开发在 BSL-2 就够了。

3.2 四种审批等级

Codex 提供了四种审批策略，从严到宽依次是：

read-only（只读）——Agent 只能阅读代码和回答问题，不能修改任何文件，不能执行任何命令。适合让 Agent 做代码审查或架构分析，零风险。在 CLI 中对应 codex --sandbox read-only。

on-request（按需审批，Auto 模式默认）——Agent 可以在工作区内自由读写文件和执行命令，但越界操作（访问工作区外的文件、使用网络等）需要你的批准。这是推荐的日常开发设置。在 CLI 中对应 codex --full-auto。

untrusted（不信任命令）——Agent 可以自由编辑文件，但运行任何可能产生副作用的命令前必须征得你的同意。适合当你信任 Agent 的代码能力，但不想让它自主执行 Shell 命令时使用。在 CLI 中对应 codex --sandbox workspace-write --ask-for-approval untrusted。

never（从不审批）——Agent 拥有完全自主权，不会在任何操作前停下来问你。如果再加上 danger-full-access 沙箱模式（CLI 中的 --yolo 旗标），连沙箱隔离也会移除。除非在容器化环境中，否则强烈不建议使用。 这相当于把实验室的防护门全部打开——效率最高，但出了事也没有任何缓冲。

3.3 网络访问：默认关门

一个常被忽视的安全细节：Codex 默认不允许 Agent 访问网络。

这意味着在 Local 和 Worktree 模式下，Agent 无法自行下载依赖、访问外部 API 或浏览网页。这是刻意为之的——防止 Agent 被提示注入（Prompt Injection）攻击引导去访问恶意网站。

如果你的任务确实需要网络访问（比如 mvn dependency:resolve），有几种方式开启：

Cloud 模式：在环境配置中开启全量网络或指定域名白名单（推荐只放行 repo.maven.apache.org、registry.npmjs.org 等必要域名）
CLI 配置：在 ~/.codex/config.toml 中为特定沙箱模式启用网络：

1 2	[sandbox_workspace_write] network_access = true

Web Search 缓存模式：Codex 内置了 Web Search 工具，默认使用缓存模式（从 OpenAI 维护的索引中返回结果，而非实时爬取），在提供搜索能力的同时降低了被注入攻击的风险

3.4 Java 项目的安全最佳实践

对于日常 Java 后端开发，推荐以下安全配置组合：

使用 on-request（Auto）模式：Agent 在工作区内自由操作，越界需审批——在效率和安全之间取得最佳平衡
保持 git status 干净再委派：确保工作区没有未提交的改动，这样即使 Agent 搞砸了，一个 git checkout . 就能回到起点
Cloud 模式下配置域名白名单：只放行 Maven Central、Spring Repo 等必要的依赖仓库地址，而不是开启全量网络
利用版本控制作为安全网：Worktree 模式天然提供隔离——Agent 的所有改动都在独立分支上，你审查后才合并

安全不是效率的对立面。就像里根的核裁军谈判一样，信任和验证完全可以并存——关键是建立恰当的检查机制，而不是在“放飞”和“管死”之间二选一。

4 AGENTS.md：对齐问题的微缩版

人工智能研究中有一个核心难题叫“对齐问题”（Alignment Problem）：如何确保一个自主行动的智能体，真正按照你的意图行事，而不是按照它自己“理解”的意图？这个问题在 GPT 和 Claude 的层面是哲学性的，但在 Codex Agent 的层面，它非常具体：你怎么让一个自主编码的 Agent 遵循你项目的架构规范、编码风格和安全约束？

答案是 AGENTS.md。

4.1 一份“入职手册”

每个有过带新人经验的工程师都知道：新人入职第一天，你不可能通过口头嘱咐让他记住所有规矩。你需要一份文档，写清楚“我们这里怎么做事”。AGENTS.md 就是这份文档——只不过读者不是人类新人，而是 AI Agent。

它放在仓库根目录，Codex 在每次启动任务时自动读取。没有它，Agent 就像一个空降到项目的新人，只能靠猜测行事；有了它，Agent 从第一秒就知道项目用什么技术栈、怎么构建、有哪些铁律不能违反。

在 Cursor 中，你可以通过多轮对话持续纠偏——Agent 犯了错，你随时可以说“不是这样，应该那样”。但 Codex 的工作模式不同，尤其在 Cloud 模式下，Agent 是异步执行的，你没有机会中途插话。AGENTS.md 是你在“发射前”唯一的对齐窗口。写得越清楚，Agent 偏离预期的概率就越低。

Temporal 团队是一个值得参考的实践：他们在 AGENTS.md 中详细写明了如何格式化代码、如何运行 Gradle 构建和测试，确保 Codex 的每次改动都符合项目要求。

来自 OpenAI 内部的一个实验更能说明问题。Sherwin Wu 透露，OpenAI 有一个团队正在维护一个 100% 由 Codex 编写的代码库——当 Agent 没按预期工作时，团队成员不会“撸起袖子自己敲代码”，而是始终让 AI 自己编写。他们发现：Agent 失败时，问题几乎总是出在上下文不足。 解决方法不是自己重写代码，而是补充文档、添加代码注释、改进代码结构，或者在仓库中增加 MD 文件——把你脑海里的“部落知识”显式化，让模型能读到。这正是 AGENTS.md 存在的意义：它不是锦上添花的文档，而是 Agent 能否正确工作的决定性因素。

4.2 Java 项目 AGENTS.md 模板

以下是一份面向 Java 后端项目的参考模板。一个好的 AGENTS.md 回答了 Agent 最关心的五个问题：这个项目是什么？怎么跑起来？代码该怎么写？什么不能碰？怎么验证？

# 项目说明

## 概述
这是一个基于 Spring Boot 3.2 的电商后端服务，使用 Java 17，Maven 构建。
项目采用分层架构：Controller → Service → Repository。

## 技术栈
- Java 17 / Spring Boot 3.2
- Spring Data JPA + MySQL 8.0
- Redis（缓存）
- JUnit 5 + Mockito（测试）
- MapStruct（DTO 转换）
- Flyway（数据库迁移）

## 构建与测试
- 编译：mvn clean compile
- 运行测试：mvn test
- 完整构建：mvn clean package
- 启动服务：mvn spring-boot:run

## 项目结构
src/main/java/com/example/shop/
├── controller/    # REST 控制器，只做参数校验和结果封装
├── service/       # 业务逻辑
├── repository/    # 数据访问层（JPA Repository）
├── entity/        # 数据库实体类
├── dto/           # 请求/响应 DTO
├── config/        # 配置类
├── exception/     # 自定义异常和全局异常处理
└── util/          # 工具类

## 编码规范
- 遵循阿里巴巴 Java 开发手册
- Controller 层不写业务逻辑，只做参数校验和 Service 调用
- 使用 @Slf4j 记录日志，禁止使用 System.out.println
- 异常统一抛出自定义 BusinessException，不要直接抛 RuntimeException
- 数据库字段用下划线命名，Java 属性用驼峰命名
- 所有 REST 接口返回统一响应格式：Result（code, message, data）

## 禁止事项
- 不要修改 src/main/resources/db/migration/ 下的已有迁移文件
- 不要修改 pom.xml 中的依赖版本（如需新增依赖请说明理由）
- 不要在循环中进行数据库查询（N+1 问题）
- 不要硬编码配置值，使用 @Value 或 @ConfigurationProperties
- 不要使用 Java 8 之前的日期 API（使用 java.time.*）

## 测试要求
- 新功能必须附带单元测试
- Service 层测试使用 Mockito mock Repository
- Controller 层测试使用 @WebMvcTest + MockMvc
- 测试方法命名：should_预期行为_when_条件
- 确保所有测试通过后再提交

4.3 对齐是一个持续过程

如果你读过《人机对齐》，你会知道对齐不是一次性的事——它需要持续的观察、反馈和修正。AGENTS.md 也是如此：

从简单开始：先写核心的构建命令、项目结构和编码规范，不需要一次性面面俱到。
记录 Agent 的“常见错误”：如果你发现 Agent 反复在某个地方犯错（比如总是忘了加 @Transactional），就把对应的规则加进去。每一条新规则，都是你从 Agent 的错误中提炼出来的“对齐补丁”。
纳入版本控制：AGENTS.md 应该和代码一起提交到 Git。团队成员都能受益，而且当项目规范变化时可以追溯。

4.4 层级化配置：从全局到局部

如果你只管理一个项目，在仓库根目录放一个 AGENTS.md 就够了。但现实世界往往更复杂——你可能有个人通用的编码偏好、公司级的规范要求、项目级的技术选型、甚至子模块级的特殊规则。这就像一家跨国公司的管理制度：总部有通用政策，区域有本地化调整，个别部门还有例外条款。

Codex 的 AGENTS.md 支持类似的层级化覆盖机制。它的发现顺序如下：

全局级：~/.codex/AGENTS.md——你个人的通用偏好，适用于所有项目。例如“始终使用中文注释”“偏好使用 pnpm 而非 npm”
项目根目录级：仓库根目录的 AGENTS.md——项目特有的技术栈、构建命令和编码规范
子目录级：各子目录下的 AGENTS.md——适用于 Monorepo 中不同模块的差异化规则

关键规则：越靠近当前工作目录的文件优先级越高。 因为 Codex 会将所有发现的文件从根往下拼接，后出现的内容会覆盖先出现的——就像 CSS 的层叠规则一样。

此外还有一个强力武器：AGENTS.override.md。当同一目录下同时存在 AGENTS.md 和 AGENTS.override.md 时，Codex 只读取 override 文件而忽略普通文件。这非常适合临时覆盖规则而不修改团队共享的 AGENTS.md——比如你在调试一个棘手的 Bug 时，临时放宽某些限制。

以一个 Java Monorepo 为例：

my-platform/
├── AGENTS.md                          # 全局规范：编码风格、Git 提交规范
├── services/
│   ├── user-service/
│   │   └── AGENTS.md                  # 用户服务：Spring Boot + JPA 规范
│   └── payment-service/
│       ├── AGENTS.md                  # 支付服务：被 override 覆盖
│       └── AGENTS.override.md         # 临时规则：调试期间允许跳过部分测试
└── frontend/
    └── AGENTS.md                      # 前端：React + TypeScript 规范

当 Codex 在 payment-service/ 目录工作时，它会依次加载：全局 ~/.codex/AGENTS.md → 根目录 AGENTS.md → payment-service/AGENTS.override.md（跳过同目录的普通 AGENTS.md）。

实用建议：

全局文件放个人偏好，项目根目录放团队规范，子目录放模块特有规则
调试完成后及时删除 AGENTS.override.md，避免它长期覆盖团队规则
所有 AGENTS.md 文件的总大小有 32KB 的默认上限（可通过 config.toml 中的 project_doc_max_bytes 调整）——写得精炼比面面俱到更重要

5 高级技巧

5.1 管理长上下文：别让工作记忆溃堤

1956 年，认知心理学家乔治·米勒发表了他最著名的论文《神奇的数字 7±2》，揭示了人类短期记忆的容量限制——我们一次大约只能记住 7 个信息单元。超过这个阈值，信息就会开始相互干扰，出现遗忘和混淆。

大语言模型面临着惊人相似的困境。虽然它们的“工作记忆”（上下文窗口）远大于人类——可以容纳数十万 token 的内容——但这并不意味着它们对窗口内的每一条信息都同样敏感。研究者和开发者的经验一致表明：当对话内容达到模型上下文容量的 30-40% 时，早期的细节开始被弱化，模型的注意力聚焦在最近的交互上。越往后，越容易出现“明明告诉过它但它就是忘了”的情况。

解决方案和人类应对记忆限制的策略如出一辙——分块（chunking）和外部化（externalization）。

多开线程，而非拉长对话

米勒发现，人类绕过 7±2 限制的方式是“组块化”——把零散信息编成有意义的单元。对 Codex 而言，这意味着把大型需求拆分为多个聚焦的线程：

线程 1：生成基本项目框架和实体类
线程 2：实现 Controller 和 Service 层
线程 3：添加认证和权限控制
线程 4：编写测试和文档

每个线程专注一个子问题，上下文更集中，出错概率更低。这不仅仅是工程技巧，而是在适应模型的认知架构。

主动要求总结

人类的另一个记忆策略是“笔记”——把重要信息写下来，释放大脑去处理新问题。对 Codex 同样适用：当一个线程的对话进行到一定长度时，让 Agent 把当前状态“写下来”：

请总结目前已完成的功能、修改的文件清单、以及尚未完成的部分。

然后在新线程的开头贴上这段总结继续工作。这比让 Agent 在一个超长对话里“记住”所有细节可靠得多——就像你不会把整本教科书背下来，而是做好笔记然后带着笔记去考试。

控制 Token 消耗

长对话消耗大量 token，既拖慢响应速度，也增加成本。OpenAI 曾展示 Codex 利用约 700 万 tokens 自主开发一个 3D 游戏的案例，但这样的用量不适用于日常开发。如果输出明显变慢，考虑终止当前线程，分段处理。

5.2 调用 Shell 命令与本地工具链

内置终端与核心节奏

每个 Codex 线程附带一个内置终端，你可以在其中执行任意 Shell 命令。这带来了一个高效的工作节奏，也是 Codex 日常使用的基本循环：

在对话中让 Agent 生成代码
切到终端运行 mvn test
如果测试失败，把错误日志复制回对话框
Agent 分析失败原因并修复
再次运行测试，直到通过

这个“编码 → 测试 → 反馈 → 修复”的循环，本质上就是控制论中的反馈回路——系统做出动作，观测结果，根据偏差修正，再次行动。闭环越短，收敛越快。

三种模式下的命令执行差异

Local / Worktree： Agent 不能自动执行命令（需你确认）。你需要手动在终端执行，复制结果反馈给 Agent。
Cloud： Agent 可以自动执行命令（沙盒环境）。你只需在 AGENTS.md 中配置好命令，Agent 会自主执行。

5.3 调试支持与 IDE 集成

喂给 Agent 错误日志

最直接的调试方式：把异常栈粘贴给 Codex。例如：

运行 mvn test 后，以下测试失败：
should_throw_when_user_not_found
错误如下：

AssertionFailedError:
Expected: ResponseStatusException
But was:  NoSuchElementException
  at UserServiceTest.java:42

请分析原因并修复 UserService 中的逻辑。

Codex 会根据异常类型、堆栈信息和测试代码定位问题——在这个例子里，它可能会发现 findById 方法直接调用了 Optional.get() 而没有做空值处理，然后改为抛出 ResponseStatusException。

让 Agent 生成调试辅助代码

当问题难以复现时，让 Agent 帮你搭建调试场景：

请为 OrderService.createOrder 中的
库存扣减逻辑添加 DEBUG 级别日志，
记录每一步的中间状态
（当前库存、扣减数量、扣减后库存）。

或者：

请编写一个单元测试来复现以下场景：
当两个线程同时调用 deductStock 时，
应该只有一个成功。

这相当于让 Agent 帮你搭好实验装置，你来观察结果——正如实验物理学家不会自己吹制每一个玻璃器皿，但一定自己解读实验数据。

MCP 与 IDE 集成

OpenAI 提供了 MCP（Model Context Protocol）让 Codex 与 IDE 协同工作。通过 MCP，Agent 可以访问 IDE 的调试接口——例如 Skyscanner 的工程师已将 Codex CLI 集成进 JetBrains IDE，使 AI 能使用断点调试和测试运行功能。对 Java 开发者而言，这意味着 Codex 有潜力通过 IDE 获取运行时信息（调用栈、变量值），从而更精准地诊断问题。目前这些集成仍需手动配置，但它展示了 AI Agent 与传统开发工具结合的方向。

5.4 Skills：教 Agent 新技能

AGENTS.md 告诉 Agent“怎么做事”，Skills 则给了 Agent“做事的工具”。如果说 AGENTS.md 是入职手册，Skills 就是新员工工位上的工具箱——手册告诉他“组装时必须用扭力扳手”，工具箱里则真的有一把扭力扳手。

Skills 是 Codex 的可自定义能力模块，让 Agent 在执行任务时可以调用特定的工具和流程。Codex 内置了一些基础 Skills（如代码理解、文档生成），但真正强大的是自定义 Skills。

一个 Java 项目的实际例子：

假设你的项目使用了自定义的代码生成器——每次新增数据库表时，需要运行 mvn generate-sources -pl :code-generator 来生成 Entity 和 Repository。这不是 Agent 能从代码里推断出来的，但你可以创建一个 Skill 来告诉它。

Skills 配置存放在 ~/.codex/skills/（全局）或项目的 .codex/skills/ 目录中。一个 Skill 本质上是一份结构化的描述，告诉 Agent 在什么场景下、用什么命令、完成什么任务。

Skills vs AGENTS.md 的区别：

AGENTS.md 是被动的“规则手册”——Agent 遵循但不主动调用
Skills 是主动的“工具”——Agent 在判断需要时会主动调用它来完成特定操作

例如，你可以创建一个“运行模块测试”的 Skill，让 Agent 在修改代码后自动知道应该运行哪个模块的测试、如何解读测试结果。在本地模式下，这让 Agent 获得了类似 Cloud 模式的自主测试能力（当然仍受沙箱限制）。

一个前瞻性提醒：不要过度搭建脚手架。 Sherwin Wu 引用过一句话：“模型会把你搭的脚手架当早餐吃掉。” 2022 年 ChatGPT 刚发布时，大家围绕模型构建了大量 Agent 框架、向量数据库生态和复杂的编排系统来“引导”模型输出。但随着模型能力迅速提升，这些脚手架正在被模型本身吞噬——更好的方法反而是去掉大量逻辑，直接信任模型，只给它基础工具。Skills 今天是有价值的，但请保持轻量，不要在上面构建过于复杂的抽象层。随着 codex-1 及后续模型的进步，你今天精心搭建的框架，明天可能需要全部拆掉。

5.5 Review 的艺术：从信任到验证

科学界有一个被奉为圭臬的原则：可证伪性。卡尔·波普尔认为，一个理论的价值不在于它声称什么是对的，而在于它提供了什么方法让别人来检验它是否是错的。同样的道理适用于 Agent 生成的代码——好的 Agent 输出不是让你“相信它是对的”，而是给你足够的证据去“验证它是否是错的”。

Codex 的 codex-1 模型在这方面做了专门设计：它会主动提供可验证证据。当 Agent 完成任务后，它不仅给你代码 diff，还会引用终端日志（“mvn test 的输出显示所有 47 个测试通过”）和具体的代码位置（“在 OrderService.java:87 添加了 @Transactional 注解”）。这些引用就是它的“实验数据”，供你审核。

OpenAI 内部已经在大规模实践这种模式。Sherwin Wu 透露，Codex 审核了 OpenAI 内部 100% 的 PR——任何进入生产环境的代码都会经过 Codex“过目”，它会提前生成改进建议。这让代码审查从原本 10 到 15 分钟的任务，缩短到 2 到 3 分钟。很多小型 PR 甚至不再需要人工审核。代码审查的本质是“第二双眼睛”，而 Codex 已经是一双非常聪明的“第二双眼睛”。

Review 三步法

面对 Agent 交付的一份 diff，建议按以下顺序审查：

第一步：结果验证。 先看测试是否通过、构建是否成功。如果 Agent 在 Cloud 模式下工作，这些信息已经附带在输出中；如果在 Worktree 模式下，你需要手动在终端运行一次。这一步回答的问题是：“它做的东西能跑吗？”

第二步：架构验证。 快速浏览 diff 的全局——改了哪些文件、新增了哪些类、修改了哪些方法签名。这一步回答的问题是：“它做的东西在正确的位置吗？”比如，一个应该只改 Service 层的重构，如果 diff 里出现了 Controller 或 Entity 的改动，就值得警惕。

第三步：细节验证。 聚焦关键路径逐行审查——事务边界、异常处理、并发控制、SQL 查询。这一步回答的问题是：“它做的东西在边界情况下也对吗？”

利用 Review 面板的内联评论

Codex App 的 Review 面板支持在 diff 上直接写评论——这比在对话框里描述问题高效得多。例如：

“这个查询缺少分页，当数据量大时会有性能问题，请加上 Pageable 参数。”

“这里的异常被 catch 后只打了日志没有重新抛出，会导致事务不回滚。”

Agent 会根据你的评论进行精准修改。这种“点对点”的反馈方式，比泛泛地说“请检查性能问题”有效得多——就像代码审查（Code Review）中，行级评论总是比笼统的“请优化”更容易落地。

6 Prompt 实战模板

管理学大师彼得·德鲁克曾说：“管理的本质不是命令，而是沟通。”这句话对 AI 编程同样成立。你写给 Agent 的 Prompt，本质上是一份委派指令——它的清晰程度直接决定了 Agent 的输出质量。一个模糊的“帮我加个接口”和一个结构化的需求描述，得到的结果可能天差地别。

以下是几个经过验证的 Prompt 模板，专为 Java 后端场景设计。它们的共同特征是：明确目标、提供约束、要求 Agent 先规划再动手。

6.1 新增 REST 接口

在本项目中新增一个 REST 接口，要求如下：

功能： 根据用户 ID 查询订单列表，支持分页
路径： GET /api/users/{userId}/orders
参数： userId（路径参数），page（默认 0），size（默认 20）
返回： Page<OrderDTO>，包含订单编号、金额、状态、创建时间

实现要求：

Controller 层只做参数校验和结果封装

Service 层处理业务逻辑

使用 Spring Data JPA 的分页查询

如果用户不存在，返回 404

返回格式遵循项目统一的 Result<T> 结构

请先列出你计划创建或修改的文件清单，确认后再开始编码。

要点： 最后一句“先列出文件清单”是这个模板的灵魂。它引入了一个轻量级的“计划-确认-执行”流程，让你在 Agent 动手之前就能发现理解偏差。

6.2 跨层重构

当前 UserController 中直接包含了用户数据的验证逻辑（邮箱格式校验、手机号校验、用户名唯一性检查），这违反了分层原则。

请重构：

将验证逻辑从 Controller 提取到 UserService

邮箱和手机号格式校验使用 javax.validation 注解（@Email, @Pattern）

用户名唯一性检查保留在 Service 层，通过 Repository 查询

保持所有现有 API 的行为不变

确保现有测试仍然通过

不要修改 UserRepository 和 User 实体类。

要点： 重构最怕的是牵一发动全身。明确声明“不要修改什么”和“保持什么不变”，就像给 Agent 画了一个施工围栏——围栏内随意施工，围栏外禁止动工。

6.3 生成单元测试

为 OrderService 编写 JUnit 5 单元测试，要求：

使用 @ExtendWith(MockitoExtension.class)

Mock 所有依赖的 Repository 和外部服务

覆盖以下场景：

正常创建订单（库存充足）

库存不足时抛出 BusinessException

用户不存在时抛出 BusinessException

订单金额计算正确（含优惠券折扣）

创建订单后库存正确扣减

测试方法命名遵循 should_预期行为_when_条件

使用 AssertJ 断言风格

生成完成后请运行 mvn test -pl :order-service 确认全部通过。

要点： 指定测试框架、Mock 方式、命名规范、断言风格——约束越多，输出越可控。最后一句指示 Agent 运行测试：在 Cloud 模式下它会自动执行；在本地模式下它会提示你手动执行。

6.4 排查 Bug

生产环境出现间歇性问题：用户下单后偶尔出现库存扣减成功但订单状态为“创建失败”的不一致情况。

请按以下步骤分析：

阅读 OrderService.createOrder 方法的完整逻辑

检查事务边界：@Transactional 注解是否正确放置

检查异常处理：是否有被 catch 后没有重新抛出的异常

检查外部调用：是否在事务内调用了外部服务（如发送消息队列），导致事务提交前外部状态已变更

给出根因分析和修复方案

先分析，不要直接改代码。分析完成后等我确认再修复。

要点： 给出结构化的排查步骤，引导 Agent 像资深工程师一样系统地分析问题。“先分析，不要直接改代码”这句话非常重要——它把 Agent 从“执行者”模式切换到“分析师”模式，避免它在没搞清楚问题之前就动手“修”出更多问题。

6.5 代码审查

请以高级 Java 工程师的视角审查以下改动（本次线程中的所有 diff），重点关注：

事务一致性：是否有遗漏的 @Transactional 或事务边界不正确

并发安全：是否有竞态条件或线程安全问题

异常处理：是否有未处理的 checked exception 或过于宽泛的 catch

性能隐患：N+1 查询、循环内数据库调用、缺少索引

安全漏洞：SQL 注入、敏感信息日志泄露、未校验的用户输入

对每个问题给出具体的文件名、行号和修复建议。

要点： 让 Agent 扮演“审查者”而非“实现者”——同一个 Agent 写的代码，换一个角色来审，往往能发现自己创作时的盲点。这和文学创作中“放一段时间再回头修改”的道理相通。

6.6 Automations：让 Agent 值夜班

Codex 支持 Automations 功能，让 Agent 定期执行例行任务——就像医院的夜班护士定时巡查病房。你可以设置：

每日代码质量检查： 让 Agent 每天扫描代码库，检查是否有新增的 TODO 未处理、测试覆盖率是否下降。
CI 失败分析： 当 CI 流水线失败时，自动让 Agent 分析失败原因并提出修复建议，结果进入收件箱。
依赖更新提醒： 定期检查 pom.xml 中的依赖是否有安全漏洞或重大版本更新。

在 OpenAI 内部，开发者已用 Automations 每日自动整理 Bug 列表、汇总 CI 失败原因、生成发布报告。你上班时打开 Codex 收件箱，昨晚的巡查报告已经在那里了。

7 实战示例：从零构建 Spring Boot REST 服务

纸上得来终觉浅。让我们通过一个完整示例，把前面所有概念串联起来。

场景： 构建一个用户管理 REST 服务，包含获取用户列表和按 ID 查询两个接口。使用 Spring Boot + 内存数据（简化起见）。本地已有 JDK 和 Maven 环境，以及一个空的 Git 仓库。

步骤 1：初始化项目

打开 Codex，选择项目目录 ~/Projects/UserService，启动新线程（选择 Worktree 模式）。发送：

使用 Spring Boot 3.2 + Java 17 初始化一个 Maven 项目，artifactId 为 user-service。
包含以下依赖：spring-boot-starter-web, spring-boot-starter-test。
创建主类 UserServiceApplication，配置 server.port=8080。
同时在项目根目录创建 AGENTS.md，写明构建命令（mvn clean compile）和测试命令（mvn test）。

Codex 会生成 pom.xml、主类、application.properties 和 AGENTS.md。在 Review 面板中检查文件结构是否符合预期。

步骤 2：实现业务逻辑

确认项目框架后，在同一线程继续：

按照以下设计实现用户管理功能：

创建 User 实体类（id: Long, name: String, email: String），放在 entity 包下

创建 UserService，内部维护一个 ArrayList 作为模拟数据源，预置 3 个用户数据。提供 findAll() 和 findById(Long id) 方法

创建 UserController，提供：

GET /api/users → 返回所有用户

GET /api/users/{id} → 返回单个用户，找不到时返回 404

Controller 通过构造函数注入 UserService

不要使用 Lombok，手动编写 getter/setter。

Codex 会在对话中描述它正在创建的文件，并在 Review 面板显示完整 diff。检查类结构、包路径、注解是否正确。

步骤 3：运行验证

切到线程的内置终端：

1	mvn spring-boot:run

启动后在另一个终端（或浏览器）访问：

1
2
3

curl http://localhost:8080/api/users
curl http://localhost:8080/api/users/1
curl http://localhost:8080/api/users/999  # 预期返回 404

如果启动失败（比如缺少依赖），把错误日志复制回对话：

应用启动失败，报错如下：[粘贴错误栈]。请分析原因并修复。

Codex 会定位问题并修改代码。这就是第 5 章提到的“编码 → 测试 → 反馈 → 修复”闭环的一次实际运转。

步骤 4：生成测试

新开一个线程（继续使用同一项目的 Worktree 模式），发送：

为 UserService 和 UserController 编写 JUnit 5 测试：

UserServiceTest：

should_return_all_users

should_return_user_when_id_exists

should_throw_when_id_not_found

UserControllerTest（使用 @WebMvcTest + MockMvc）：

should_return_200_and_user_list

should_return_200_and_single_user

should_return_404_when_user_not_found

生成后请确认所有文件路径正确（放在 src/test/java 对应的包下）。

检查测试代码，然后在终端运行 mvn test。如果有测试未通过，反馈给 Agent 修正。

步骤 5：代码清理

所有测试通过后，让 Codex 收尾：

请检查整个项目：

为所有 public 方法添加 JavaDoc 注释

检查是否有冗余的 import

确保代码风格一致（缩进、空行等）

生成一段简短的 README.md，说明如何构建和运行

确认无误后，在应用中提交 Git commit，将 worktree 的改动合并回主分支。一个完整的 REST 服务就这样在 Codex Agent 的帮助下成型了。五个步骤，两个线程，整个过程你没有手写一行业务代码——但你审查了每一行。

8 团队协作：从单人塔台到空管中心

前面所有章节都聚焦于一个人如何高效使用 Codex。但软件开发从来不是一个人的战争——它是一个团队的协作。如果说单人使用 Codex 是一个塔台管制员指挥飞机，那么团队使用 Codex 就是建立了一个完整的空管中心——有雷达屏幕（GitHub PR），有无线电通信（Slack），有航班调度表（Linear）。

Codex 原生支持三大协作平台的集成，把 Agent 的工作融入团队现有的工作流。

8.1 GitHub 集成：PR 驱动的工作流

这是最核心的集成。在 Cloud 模式下，Agent 完成任务后会自动创建 Pull Request——不是给你一堆代码让你手动粘贴，而是一个规规矩矩的 PR，包含完整的 diff、提交信息，甚至附带测试运行结果。

完整流程：

在 Codex 中连接你的 GitHub 仓库（首次需要授权）
创建 Cloud 模式任务：“为 OrderService 添加批量导出功能”
Agent 在云端沙盒中克隆仓库、编写代码、运行测试
完成后自动创建 PR，标题和描述由 Agent 根据改动内容生成
团队成员在 GitHub 上正常 Review、评论、请求修改
审查通过后合并——和人类开发者提交的 PR 走完全相同的流程

GitHub Action：让 Codex 融入 CI/CD

更进一步，Codex 提供了官方 GitHub Action，可以在 CI/CD 流水线中自动调用 Agent。典型的使用场景：

Issue 自动修复： 当有人创建 Bug Issue 时，GitHub Action 自动触发 Codex 分析问题并提交修复 PR
PR 自动审查： 每次有新 PR 提交时，让 Codex Agent 做一次自动化代码审查，将发现的问题以评论形式写在 PR 上
依赖更新： 定期让 Agent 检查并更新过时的依赖版本

在 .github/workflows/ 中配置类似如下：

name: Codex Auto Review
on:
  pull_request:
    types: [opened, synchronize]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: openai/codex-action@v1
        with:
          task: "review"
          prompt: "以高级 Java 工程师视角审查此 PR，重点关注事务一致性、并发安全和性能隐患"

8.2 Slack 集成：实时通知与触发

将 Codex 连接到 Slack 后，Agent 的工作状态会实时推送到指定频道：

任务开始时发送通知：“Codex Agent 开始处理：为 UserService 添加分页查询”
任务完成时发送结果：“✅ 已完成，PR #42 已创建，所有测试通过”
任务失败时发送告警：“❌ 构建失败，3 个测试未通过，详见 Codex 收件箱”

更强大的是反向触发——团队成员可以直接在 Slack 中向 Codex 发指令。想象一下这个场景：周五下午，QA 在 Slack 里报告了一个 Bug，你直接在频道里 @Codex 说“分析一下 OrderService 中订单状态不一致的问题”，Agent 立刻开始工作，几分钟后在同一个频道里回复分析结果。这比打开 IDE、切换分支、定位代码要快得多——尤其是当你不在工位的时候。

8.3 Linear 集成：从 Issue 到 PR 的自动闭环

对于使用 Linear 做项目管理的团队，Codex 可以打通从需求到交付的完整链路：

PM 在 Linear 中创建 Issue：“用户管理模块需要支持批量导入功能”
将 Issue 分派给 Codex Agent（通过 Linear 集成配置）
Codex 自动读取 Issue 描述，在 Cloud 模式下开始实现
完成后自动创建 GitHub PR，并在 PR 描述中关联 Linear Issue
PR 合并后，Linear Issue 自动流转为“已完成”

这形成了一个完整的闭环：Issue → Agent 实现 → PR → Review → 合并 → Issue 关闭——中间不需要任何人手动操作流程性的事务。开发者可以把精力集中在真正需要人类判断的环节：需求澄清、架构决策和代码审查。

8.4 团队落地建议

从简单任务开始： 先用 Codex 处理团队中“人人都觉得烦但必须做”的事情——补单元测试、更新 API 文档、修复 lint 告警。这些低风险任务能帮团队建立信心。
统一 AGENTS.md： 团队共用一份 AGENTS.md，确保不同人委派的任务遵循相同的规范。把它当做“团队协作协议”来维护。
建立 Review 文化： Agent 提交的 PR 必须和人类提交的 PR 走完全相同的审查流程——不能因为是 AI 写的就跳过审查，也不能因为是 AI 写的就格外严苛。标准应该是统一的。
渐进式信任： 先 Worktree 模式，观察一段时间后再过渡到 Cloud 模式。就像委派新员工一样——先让他做小事证明能力，再逐步交给他更大的责任。

9 Codex vs Cursor：何时用哪个

心理学家丹尼尔·卡尼曼在《思考，快与慢》中提出了两种认知模式：系统 1 是快速的、直觉的、自动化的；系统 2 是缓慢的、深思熟虑的、有意识的。Cursor 像系统 1——你和 AI 在快速交互中思考，逐行迭代，实时反馈；Codex 像系统 2——你花时间想清楚要什么，写好指令，然后让 Agent 在后台深度执行。

Cursor — AI 增强的本地 IDE。你在环内实时交互，逐行建议，精细控制。单线程，运行在本地，可配置多种模型。适合精细调试、交互式探索、学习新技术。

Codex — AI Agent 指挥中心。你在环外异步审查，整块任务完整交付。多 Agent 并行，支持本地和云端，使用 codex-1 专用模型。适合批量任务、功能开发、流程自动化。

9.1 两个”不习惯”

当你从 Cursor 切换到 Codex 做日常开发，很可能遭遇两种微妙的不适感：第一，Codex 的反馈节奏明显更慢，不像 Cursor 那样”短平快”；第二，你发现自己几乎不再逐行阅读代码——效率虽然提升了，心里却反而没了底。

先看反馈慢。上文用卡尼曼的系统 1 / 系统 2 做了类比：Cursor 的体验更接近系统 1——改一点、跑一下、马上看到结果，错误与修复之间距离极短，体感流畅。而 Codex 是典型的系统 2：它会自行规划、执行一连串动作，然后一次性把成果端上来。这种长程自治模式在复杂任务上潜力巨大，代价则是等待变长、中间过程不透明、掌控感下降。于是你很容易觉得它”慢”、”钝”，甚至不如 Cursor 灵敏。

再看没底。这种感觉的根源，并非你没有亲手写代码，而是你失去了过去那套隐性的验证仪式：改了一行，你知道可能影响哪里；跑测试，看日志，确认行为符合预期——这些微小的确认堆叠在一起，构成了安全感。现在 Agent 一次交付一大块修改，你既没参与每一步推理，也没逐行阅读，自然出现一种”交付是交付了，但不知道靠不靠谱”的空心感。

9.2 从”看代码”到”看证据链”

破解这两个不适感的关键，在于一次认知转换。

试想：如果这段代码不是 AI 写的，而是一位同事提的 Pull Request，你会怎么决定能不能 merge？你大概率不会逐行读完所有代码——你依赖的是一套证据：PR 描述了什么问题、改了哪些东西、测试是否通过、有没有明显的风险点。换句话说，真正让你安心的从来不是”我亲手写了这段代码”，而是”我有足够的证据相信它是对的，并且出了事能控得住”。

当你把同样的审核门槛用在 AI 的交付上，心态会稳定很多：你不需要盲目信任 Agent，你只需要像审核同事的 PR 一样审核证据。

这套证据可以浓缩为五类：

目标证据——它解决了什么问题，为什么要这么改，这次不解决什么
正确性证据——有没有复现用例、关键路径测试、回归是否全绿
风险证据——边界条件、性能、安全、权限等风险点是否被识别并缓解
可观测性证据——日志、指标、报警是否足以让你在上线后快速发现并定位问题
可回滚证据——如果判断失误，能否快速撤回或降级，尤其涉及数据结构变更时

对”反馈慢”，方向不是回到逐行写代码，而是把 Codex 的长程任务主动拆成里程碑式的短回路：先让 Agent 输出计划，每一步跑验证，每完成一个阶段就停下来等你验收，确认后再继续推进——这在第 5.1 节”管理长上下文”中已有详细讨论。对”没底”，则把交付格式改成”同事式 PR”：让 Agent 每次输出变更摘要、测试方式与结果、风险与缓解、观测点、回滚方案。你审的不是每一行实现细节，而是这些能让你做出合并决策的证据。

这与第 5.5 节”Review 的艺术”中的三步法一脉相承——结果验证、架构验证、细节验证，本质上都是在构建证据链。这里只是把视角从单次 Review 扩展到了整个工作流。

9.3 角色升级与组合使用

当你接受自己正在从”写代码的人”转向”对交付质量负责的人”，上面两个问题便不再是障碍，而是一次角色升级的信号：AI 负责产出与执行，你负责定义目标、设定验证门槛、审查证据、做合并决策。效率不会丢，掌控感也能回来——前提是你把过去依赖”亲手写”的安全感，升级为依赖”证据链”的安全感。

这也呼应了引言中的比喻：管制员不驾驶任何一架飞机，但他通过雷达、通信和规程，对每一架飞机的安全负全责。从驾驶员到塔台，变的是操作方式，不变的是责任标准。

理解了这层关系，Codex 与 Cursor 就不再是二选一的竞争工具，而是一对互补的系统——正如人类大脑并非只用系统 1 或系统 2，而是根据任务特征灵活切换。很多团队的实践是：

日常编码用 Cursor： 写小段代码、重构、Debug、交互式探索方案——系统 1 式的快速迭代
成块任务用 Codex： 生成样板代码、批量 CRUD、补全测试、跨文件重构——系统 2 式的深度执行
批量修复用 Codex Cloud： 一次性修复多个独立 Bug，每个 Bug 一个线程，稍后统一 Review PR

一个实际的工作流可能是：先在 Cursor 里用 Plan 模式讨论技术方案，确认后用 Codex 的 Worktree 模式并行启动多个 Agent 实现各个模块，最后回到 Cursor 做精细调整和集成调试。而在每个环节，你关注的不再是”我有没有亲手写这行代码”，而是”我有没有足够的证据做出合并决策”。

10 常见问题与使用建议

Q1: Agent 线程卡住不动了怎么办？

先检查几个常见原因：

macOS 权限弹窗： Codex 读写受保护目录（Desktop、Documents 等）时，系统会弹出权限请求。如果弹窗被其他窗口遮挡，Agent 就一直在等。检查系统通知或切换到 Codex 窗口看是否有待确认的弹窗。
Git 锁文件： 在终端运行 git status。如果提示 .git/index.lock 存在，说明上一次 Git 操作异常中断。删除锁文件即可：rm .git/index.lock。
任务本身太复杂： 如果 Agent 长时间无输出，可能是任务范围过大导致模型陷入了过深的推理链。终止线程，将任务拆小重试。

Q2: 如何防止 Agent 改坏关键文件？

最有效的三道防线：

Worktree 模式： 所有改动都在隔离分支上，不影响主代码。你审查 diff 后才决定是否合并。
AGENTS.md 中声明禁区： 明确写出“不要修改 xxx 目录/文件”。Agent 会遵循这些约束。
CI 卡口： 在合并前跑完整的测试和 lint 检查。一旦 Agent 的改动破坏了核心功能，CI 会立刻暴露。

真实踩坑案例： 有用户让 Codex 在 Cloud 模式下优化 SQL 查询，Agent 不仅改了 Service 层的查询逻辑，还“顺手”修改了 resources/db/migration/ 下的 Flyway 迁移文件——这在生产环境中是灾难性的，因为已执行过的迁移文件不允许修改。这个故事完美地说明了“对齐问题”的日常版本：Agent 确实在“优化”，但它不理解“哪些东西不能碰”这条隐性规则。解决办法很简单：在 AGENTS.md 中加一句“db/migration/ 目录下的已有文件禁止修改，如需变更数据库结构请创建新的迁移文件”。

Q3: Cloud 模式下 Agent 找不到项目的私有 Maven 依赖怎么办？

Cloud 模式在 OpenAI 的沙盒中运行，无法访问你公司内网的 Maven 私服（如 Nexus、Artifactory）。解决方案：

方案一： 如果私有依赖不影响编译（只是运行时需要），在 AGENTS.md 中告诉 Agent 跳过：mvn compile -pl :your-module -am -Dmaven.test.skip=true。
方案二： 对于必须依赖私有库的项目，使用 Worktree 模式替代 Cloud 模式——本地环境能正常解析私有依赖。
方案三： 将私有依赖发布到 GitHub Packages 等公网可访问的仓库，并在 pom.xml 中配置对应的 repository。

Q4: 如何控制 Token 消耗？

几个实用策略：

限定输出范围： 不要说“帮我看看这个项目有什么问题”，而是说“检查 OrderService 中 createOrder 方法的事务一致性”。范围越精确，消耗越少。
小步迭代： 一次处理一个功能点，不要试图在一个线程里完成整个模块。
善用 AGENTS.md： 把项目背景信息写在 AGENTS.md 中，就不需要每次对话都重复说明——这和你给新同事写入职文档是一个道理，一次投入，长期受益。
监控线程时长： 如果一个线程的响应变慢、输出质量下降，说明上下文已经过长。果断开新线程。

Q5: 有哪些提升效果的小技巧？

一个线程一个主题： 不要在同一个线程里又改 Bug 又加功能。就像你不会在一封邮件里同时讨论三个不相关的议题——信息越聚焦，沟通越高效。
先分析后编码： 对复杂任务，总是在 Prompt 末尾加上“先列出你的方案/计划，确认后再开始编码”。这避免了 Agent 理解偏差导致的大量返工。
善用 Review 面板的评论功能： 直接在 diff 上写评论（如“这里需要加事务注解”“这个字段名应该用 camelCase”），然后让 Agent 根据评论修改。这种定向反馈比重新描述需求高效得多。
让 Agent 解释自己的改动： 如果你不确定某段生成代码的逻辑，直接问“请解释你在 OrderService 第 45 行使用 CompletableFuture 的原因”。理解 Agent 的思路有助于你做出更准确的判断。
Worktree + 并行的黄金组合： 当你有多个独立的任务时（如三个不同的 Bug），同时开三个 Worktree 线程并行处理，然后逐一 Review 合并。这是 Codex 相对于 Cursor 最大的效率优势——空中交通管制员同时引导多架飞机着陆，而不是一架一架排队等。

11 结语：从塔台到空管网络

1956 年那位走上塔台的管制员，大概不会想到，半个多世纪后全球的空中交通管制已经演变成一个由卫星、雷达、自动化系统和数千名专业人员组成的庞大网络。从一个人拿着望远镜盯跑道，到一个全球协作的空管体系——技术在变，但核心原则始终如一：清晰的通信、可靠的监控、明确的权责。

回顾本文走过的路径，你会发现它描绘了一条类似的演化路线：

第 1 章让你认识了 Codex 的全貌——从桌面应用到命令行、IDE 插件和 Web 版，了解你手中工具的完整能力边界
第 2 章帮你选择了合适的信任层级——Local、Worktree、Cloud，从“你做我看”到“你全权负责”
第 3 章建立了安全底线——沙箱隔离和审批策略，确保信任不会变成放纵
第 4 章解决了对齐问题——AGENTS.md 让 Agent 从第一秒就知道“我们这里怎么做事”
第 5-7 章提供了实战武器——上下文管理、Shell 集成、Skills、Review 技巧、Prompt 模板和完整示例
第 8 章把视角从个人扩展到团队——GitHub、Slack、Linear 集成，让 Agent 成为团队工作流的一部分

每一步都在做同一件事：建立更好的验证闭环。模式选择决定了闭环的粒度，安全沙箱决定了闭环的边界，AGENTS.md 决定了闭环的标准，Review 工作流决定了闭环的质量。

站在 2026 年的今天，Agent 式编程仍处于早期。Sherwin Wu 给出了一个明确的方向预判：未来 12 到 18 个月，模型将从“分钟级任务”进化到可以连贯完成“多小时甚至一天”的任务。围绕这种长时程 Agent 构建的产品会完全不同于今天的交互式工具。他的核心建议是：为模型将要去的方向构建，而不是为模型今天的状态构建。那些真正做得好的产品，往往围绕一种“理想能力”设计——今天可能只实现了 80%，但随着模型变强，某一天就会彻底跑通。

codex-1 模型会继续进化，工具链会日趋完善，人机协作的模式也会不断探索出新的可能。但有一件事不会变：当 AI Agent 越来越自主，工程师的核心竞争力会从“写代码的速度”转向“定义问题的精度”和“验证方案的能力”。

你不需要成为更快的打字员。你需要成为更好的塔台——发出清晰的指令，维护可靠的雷达，做出果断的决策。天空中的飞机会越来越多，但只要你的雷达系统足够好，你就能确保每一架都安全着陆。